home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir31 / gusutils.zip / GUS.DOC < prev    next >
Text File  |  1994-02-08  |  11KB  |  304 lines
  1. (****************************************************************************)
  2. (* Module     : GUS.DOC                                                     *)
  3. (* Verion     : 0.6ß                                                        *)
  4. (* Date       : Thu Feb 3, 1994                                             *)
  5. (* Pascal     : TP 7.0                                                      *)
  6. (****************************************************************************)
  7. (*                                                                          *)
  8. (* NOTICE OF COPYRIGHT AND OWNERSHIP OF SOFTWARE:                           *)
  9. (*                                                                          *)
  10. (* Copyright (C) 1993, 1994 by MESS Computer Services.                      *)
  11. (* Portions Copyright (C) 1993, 1994 by TBP Electronics Ltd.                *)
  12. (* All rights reserved.                                                     *)
  13. (*                                                                          *)
  14. (****************************************************************************)
  15. (* MESS Computer Services V.O.F.        MM   MM  EEEEEE   SSSSS   SSSSS     *)
  16. (* Jadestraat 54                        M M M M  E       S       S          *)
  17. (* 4817 JK  Breda                       M  M  M  EEEE     SSSS    SSSS      *)
  18. (* The Netherlands                      M     M  E            S       S     *)
  19. (*                                      M     M  EEEEEE  SSSSS   SSSSS      *)
  20. (* Tel: +31-76 22 34 31                                                     *)
  21. (* Fax: +31-76 20 46 23               Many Efforts for Structured Systems   *)
  22. (* Email: appel@stack.urc.tue.nl                                            *)
  23. (****************************************************************************)
  24.  
  25.  
  26. GusFind : Boolean
  27. -------
  28.       At first it looks for the ULTRASND environment variable. If it
  29.       exists, the base address of the GUS is being read. If it doesn't
  30.       exist (or the address is invalid), it tries to detect the GUS
  31.       at very addres from 200h to 2A0h. Returns False when no GUS was
  32.       found, otherwise True.
  33.  
  34.       GusBase (word)
  35.       -------
  36.       Is set to the GUS I/O base address (2x0), if no GUS board is found
  37.       or Mega-Em is active then GusBase is 0.
  38.  
  39.       GusMemory (word)
  40.       ---------
  41.       Contains the amount of GUS memory installed in Kb, i.e. 256, 512, 768,
  42.       or 1024. If no GUS board is found or there is no memory on the GUS
  43.       board installed or Mega-Em is active then GusMemory is 0.
  44.  
  45.       GusEnvironment (string)
  46.       --------------
  47.       Contains the "ULTRASND" environment variable (or an empty string if it
  48.       doesn't exist).
  49.  
  50.       GusVoices (byte)
  51.       ---------
  52.       Contains the maximum number of active voices as set on the GUS.
  53.  
  54.       GusDataConvert (boolean)
  55.       --------------
  56.       This variable is default set to False. The procedures GusWrite and
  57.       GusRead use this variable to convert the data to and from
  58.       2 complements. The GUS works only with data in 2 complements format
  59.       (signed) so if you want to play a sample in 1 complements format
  60.       (unsigned) you must set GusDataConvert to True, on the otherhand if
  61.       you want to play a sample in 2 complements format (signed) you must
  62.       set GusDataConvert to False.
  63.  
  64.       2CMP (signed)   -> GusDataConvert := False;
  65.       1CMP (unsigned) -> GusDataConvert := True;
  66.  
  67.       GusData16Bits (boolean)
  68.       -------------
  69.       This variable is default set to False. The procedures GusWrite and
  70.       GusRead use this variable to convert the data to and fro 2 complements.
  71.       If GusData16Bits is set to True GusWrite and GusRead know that they
  72.       have to convert 16 Bits data.
  73.  
  74.        8 Bits -> GusData16Bits := False;
  75.       16 Bits -> GusData16Bits := True;
  76.  
  77.  
  78. MegaEm : Boolean
  79. ------
  80.       This function checks if Mega-Em is active, returns True when active,
  81.       otherwise False.
  82.  
  83.  
  84. GusInit (VoicesMax : byte)
  85. -------
  86.       This procedure resets the GF1 and initializes all the registers to
  87.       there default settings. The maximum number of active voices is set
  88.       to the new value given by VoicesMax.
  89.  
  90.       You'll need this procedure in two cases:
  91.  
  92.       1. You want to change the maximum number of active voices.
  93.          Let's say GusVoices is 14, but you need 24 voices. Simply
  94.          type GusInit (24).
  95.  
  96.       2. You want to reset the GF1 because you are not sure if all the
  97.          registers are properly set. Simply type GusInit (GusVoices).
  98.  
  99.  
  100. GusMixer (Output : ShortInt)
  101. --------
  102.       You can change the GUS mixer at any time. The mixer can turn on the
  103.       line out, line in and mic in.
  104.  
  105.       There are three constants defined:
  106.  
  107.          LineOut = -1
  108.          LineIn  = -2
  109.          MicIn   = 4
  110.  
  111.       So you can simply type GusMixer (LineOut+LineIn) and now the line in
  112.       and line out are enabled. If you want all mixer channels to be
  113.       disabled then you simply type GusMixer (0).
  114.  
  115.  
  116. GusPoke (Address : LongInt; Value : Byte)
  117. -------
  118.       Writes the value into the GUS memory. These are the maximum
  119.       addresses:
  120.  
  121.          256 kb memory: 0 -  262144  ($3FFFF)
  122.          512 kb memory: 0 -  524288  ($7FFFF)
  123.          768 kb memory: 0 -  786432  ($BFFFF)
  124.         1024 kb memory: 0 - 1048576  ($FFFFF)
  125.  
  126.       Note: The value is a byte! this byte is directly dumped into the
  127.             GUS memory (without any conversion).
  128.  
  129.  
  130. GusPeek (Address : LongInt) : Byte
  131. -------
  132.       Read a byte from the GUS memory. See also GusPoke.
  133.  
  134.  
  135. GusWrite (Addres : LongInt; var Buffer; Count : Word)
  136. --------
  137.       GusWrite writes Count or fewer bytes to the GUS memory from memory,
  138.       starting at the first byte occupied by Buffer to the GUS memory
  139.       pointed to by Address. Conversion is done according to the setting
  140.       of GusDataConvert (See also GusFind: GusDataConvert, GusData16Bits).
  141.  
  142.  
  143. GusRead (Addres : LongInt; var Buffer; Count : Word)
  144. --------
  145.       Reads from GUS memory to the memory buffer. See also GusWrite.
  146.  
  147.  
  148. VoiceInit (Voice : Byte)
  149. ---------
  150.       The following procedures and functions affect only one voice. The
  151.       first parameter specifies the voice, it must be between 0 and
  152.       GusVoices - 1. For example, if you have called GusInit(14), the
  153.       voice number can range from 0 to 13.
  154.  
  155.       VoiceInit set all parameters of a specific voice to there default
  156.       (zero) value.
  157.  
  158.  
  159. VoiceBalance (Voice : Byte; Balance : Byte)
  160. ------------
  161.       You can change the balance at any time (panning effect). The
  162.       balance value ranges from 0 to 15, 0 being far left, 15 being far
  163.       right, and 7 is approximately middle.
  164.  
  165.       There are three constants defined:
  166.  
  167.          Left   = 0
  168.          Middle = 7
  169.          Right  = 15
  170.  
  171.       So you can simply type VoiceBalance (0, Right) and now voice 0
  172.       sounds through the right speaker only.
  173.  
  174.  
  175. VoiceVolume (Voice : Byte; Volume : Word)
  176. -----------
  177.       Sets the volume (between 0 and 4095 = $FFF) for that voice. It's
  178.       not a linear volume, but a logarithmic one. Best way, you create
  179.       an array with the volumes you need.
  180.  
  181.          $FFF = full volume
  182.          $EFF = half volume
  183.          $DFF = quarter volume
  184.          $CFF = eighth volume
  185.          $BFF = sixteenth volume etc.
  186.  
  187.       The lowest hex digit can be used to fine tune the volume. $FF0 is
  188.       almost as loud as $FFF. You can change the volume at any time.
  189.  
  190.  
  191. VoiceFreq (Voice : Byte; Freq : Word)
  192. ---------
  193.       Sets the Frequency (in bytes/second). If you have a 16 bits sample
  194.       you have to multiply the frequency by two to get the frequency in
  195.       bytes/second. You can change the frequency at any time.
  196.  
  197.  
  198. VoiceMode (Voice : Byte; Mode : Byte)
  199. ---------
  200.       Sets various parameters. Mode is one or more of the following:
  201.  
  202.          Bit8, Bit16     : selects 8 or 16 bit samples.
  203.          LoopOff, LoopOn : specifies whether to loop this voice.
  204.          UniDir, BiDir   : unidirectional or bidirectional.
  205.          Forw, Backw     : play the sample forward or backward.
  206.  
  207.       For example, you can type VoiceMode (0,Bit8+LoopOn+UniDir+Forw). If
  208.       you omit any of the modes, the default is Bit8+LoopOff+UniDir+Forw.
  209.  
  210.  
  211. VoiceSample (Voice : Byte; Start, LoopStart, LoopEnd : LongInt)
  212. -----------
  213.       Specifies where the sample is located in the GUS memory. Start is
  214.       the start address of the sample (where the GUS starts playing). It
  215.       should be 32 bit aligned, i.e. bit 0 and 1 should be 0. LoopStart
  216.       and LoopEnd define the looping range. LoopStart MUST BE smaller
  217.       than LoopEnd. Note that the actual loop ends one byte before LoopEnd.
  218.  
  219.       If you've disabled looping (see also VoiceMode), just set LoopStart
  220.       the same as Start (or any other value smaller than LoopEnd).
  221.  
  222.       You can use VoiceSample at any time -- even while the voice is
  223.       playing.
  224.  
  225.  
  226. VoiceStart (Voice : Byte)
  227. ----------
  228.       Starts playing the specified voice.
  229.  
  230.  
  231. VoiceStop (Voice : Byte)
  232. ---------
  233.       Stops playing the specified voice.
  234.  
  235.  
  236. VoiceActive (Voice : Byte) : Boolean
  237. -----------
  238.       Returns False if the specified voice is stopped. Otherwise this
  239.       function return True, the voice is active.
  240.  
  241.  
  242. GetVoiceLoc (Voice : Byte, Location : Byte) : LongInt
  243. -----------
  244.       Get one of the GF1 pointers of the specified voice.
  245.  
  246.       There are three constants defined:
  247.  
  248.          Current   = $8A
  249.          LoopStart = $82
  250.          LoopEnd   = $84
  251.  
  252.       So you can simply type GusVoiceLoc (0, Current) and the current
  253.       location of voice 0 will be returned.
  254.  
  255.  
  256. RampRange (Voice : Byte; Lower, Upper : Word)
  257. ---------
  258.       Specify the lower and upper volume level of the volume ramp. These
  259.       are values between $000 and $FFF (see also VoiceVolume), but the
  260.       lower hex digit (lower 4 bits) is ignored.
  261.  
  262.       Note: Lower must be less than Upper, even when ramping down.
  263.  
  264.  
  265. RampRate (Voice : Byte; Scale, Rate : Byte)
  266. --------
  267.       Sets the speed of the ramping. Scale must be between 0 and 3,
  268.       Rate must be between 0 and 63 (the less, the faster).
  269.  
  270.       Scale  increase or decrease volume by the Rate value per
  271.       -----  -------------------------------------------------
  272.          0      1 Byte
  273.          1      8 Bytes
  274.          2     16 Bytes
  275.          3    512 Bytes
  276.  
  277.  
  278. RampMode (Voice : Byte; Mode : Byte)
  279. --------
  280.       Sets various ramp parameters. Mode is one or more of the following:
  281.  
  282.          LoopOff, LoopOn: specifies whether to loop the volume ramp.
  283.          UniDir, BiDir  : unidirectional or bidirectional.
  284.          Up, Down       : slide up or down.
  285.  
  286.       For a vibrato, you should usually type RampMode (Voice,LoopOn+BiDir),
  287.       up or down doesn't matter.
  288.  
  289.       For a volume slide, you should type RampMode (Voice,LoopOff+UniDir+Up),
  290.       this will slide the volume up (from lower to upper level).
  291.  
  292.       Simply replace "Up" by "Down" to slide the volume down (from upper to
  293.       lower level).
  294.  
  295.  
  296. RampStart (Voice : Byte)
  297. ---------
  298.       Starts the volume ramping of the specified voice.
  299.  
  300.  
  301. RampStop (Voice : byte)
  302. --------
  303.       Stops the volume ramping of the specified voice.
  304.